home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -serious- / programming / c / icu-1.3.1 / icu-bin / include / ucnv.h < prev    next >
C/C++ Source or Header  |  2000-02-23  |  23KB  |  590 lines
  1. /*******************************************************************************
  2. *                                                                              *
  3. * COPYRIGHT:                                                                   *
  4. *   (C) Copyright International Business Machines Corporation,  1999           *
  5. *   Licensed Material - Program-Property of IBM - All Rights Reserved.         *
  6. *   US Government Users Restricted Rights - Use, duplication, or disclosure    *
  7. *   restricted by GSA ADP Schedule Contract with IBM Corp.                     *
  8. *                                                                              *
  9. *******************************************************************************/
  10. /*
  11.  *  ucnv.h:
  12.  *  External APIs for the ICU's codeset conversion library
  13.  *  Bertrand A. Damiba
  14.  *
  15.  * Modification History:
  16.  *
  17.  *   Date        Name        Description
  18.  *   04/04/99    helena      Fixed internal header inclusion.
  19.  */
  20.  
  21.  
  22. #ifndef UCNV_H
  23. #define UCNV_H
  24.  
  25. #include "utypes.h"
  26. #include "ucnv_bld.h"
  27. #include "ucnv_err.h"
  28.  
  29. U_CDECL_BEGIN
  30.  
  31. typedef void (*UConverterToUCallback) (UConverter *,
  32.                   UChar **,
  33.                   const UChar *,
  34.                   const char **,
  35.                   const char *,
  36.                   int32_t* offsets,
  37.                   bool_t,
  38.                   UErrorCode *);
  39.  
  40. typedef void (*UConverterFromUCallback) (UConverter *,
  41.                     char **,
  42.                     const char *,
  43.                     const UChar **,
  44.                     const UChar *,
  45.                     int32_t* offsets,
  46.                     bool_t,
  47.                     UErrorCode *);
  48.  
  49. U_CDECL_END
  50.  
  51.  
  52. /**
  53.  * Creates a UConverter object with the names specified as a C string.
  54.  * The actual name will be resolved with the alias file.
  55.  * if <TT>NULL</TT> is passed for the converter name, it will create one with the
  56.  * getDefaultName return value.
  57.  * @param converterName : name of the uconv table
  58.  * @param err outgoing error status <TT>U_MEMORY_ALLOCATION_ERROR, TABLE_NOT_FOUND</TT>
  59.  * @return the created Unicode converter object, or <TT>NULL</TT> if an error occured
  60.  * @see ucnv_openU
  61.  * @see ucnv_openCCSID
  62.  * @see ucnv_close
  63.  */
  64.  
  65. U_CAPI
  66. UConverter* U_EXPORT2 ucnv_open   (const char *converterName,
  67.                    UErrorCode * err);
  68.  
  69.  
  70. /**
  71.  * Creates a Unicode converter with the names specified as unicode string. The name should be limited to
  72.  * the ASCII-7 alphanumerics range. The actual name will be resolved with the alias file.
  73.  * if <TT>NULL</TT> is passed for the converter name, it will create one with the
  74.  * getDefaultName return value.
  75.  * @param converterName : name of the uconv table in a zero terminated Unicode string
  76.  * @param err outgoing error status <TT>U_MEMORY_ALLOCATION_ERROR, TABLE_NOT_FOUND</TT>
  77.  * @return the created Unicode converter object, or <TT>NULL</TT> if an error occured
  78.  * @see ucnv_open
  79.  * @see ucnv_openCCSID
  80.  * @see ucnv_close
  81.  */
  82. U_CAPI UConverter* U_EXPORT2 ucnv_openU (const UChar * name,
  83.                        UErrorCode * err);
  84.  
  85.  
  86.  
  87. /**
  88.  * Creates a UConverter object using a CCSID number.
  89.  * @param codepage : codepage # of the uconv table
  90.  * @param platform : codepage's platform (now only <TT>IBM</TT> supported)
  91.  * @param err error status <TT>U_MEMORY_ALLOCATION_ERROR, TABLE_NOT_FOUND</TT>
  92.  * @return the created Unicode converter object, or <TT>NULL</TT> if and error occured
  93.  * @see ucnv_open
  94.  * @see ucnv_openU
  95.  * @see ucnv_close
  96.  */
  97.  
  98. U_CAPI UConverter* U_EXPORT2 ucnv_openCCSID (int32_t codepage,
  99.                        UConverterPlatform platform,
  100.                        UErrorCode * err);
  101.  
  102.  
  103. /**
  104.  * Deletes the unicode converter.
  105.  * @param converter the converter object to be deleted
  106.  * @see ucnv_open
  107.  * @see ucnv_openU
  108.  * @see ucnv_openCCSID
  109.  */
  110. U_CAPI void  U_EXPORT2 ucnv_close (UConverter * converter);
  111.  
  112.  
  113.  
  114. /**
  115.  * Fills in the output parameter, subChars, with the substitution characters
  116.  * as multiple bytes.
  117.  * @param converter: the Unicode converter
  118.  * @param subChars: the subsitution characters
  119.  * @param len: on input the capacity of subChars, on output the number of bytes copied to it
  120.  * @param  err: the outgoing error status code.
  121.  * If the substitution character array is too small, an
  122.  * <TT>U_INDEX_OUTOFBOUNDS_ERROR</TT> will be returned.
  123.  * @see ucnv_setSubstChars
  124.  */
  125.  
  126. U_CAPI void U_EXPORT2
  127.     ucnv_getSubstChars (const UConverter * converter,
  128.             char *subChars,
  129.             int8_t * len,
  130.             UErrorCode * err);
  131.  
  132. /**
  133.  * Sets the substitution chars when converting from unicode to a codepage. The
  134.  * substitution is specified as a string of 1-4 bytes, and may contain <TT>NULL</TT> byte.
  135.  * The fill-in parameter err will get the error status on return.
  136.  * @param converter the Unicode converter
  137.  * @param subChars the substitution character byte sequence we want set
  138.  * @param len the number of bytes in subChars
  139.  * @param err the error status code.  <TT>U_INDEX_OUTOFBOUNDS_ERROR </TT> if
  140.  * len is bigger than the maximum number of bytes allowed in subchars
  141.  * @see ucnv_getSubstChars
  142.  */
  143.  
  144. U_CAPI void U_EXPORT2
  145.     ucnv_setSubstChars (UConverter * converter,
  146.             const char *subChars,
  147.             int8_t len,
  148.             UErrorCode * err);
  149.  
  150.  
  151.  
  152. /**
  153.  * Fills in the output parameter, errBytes, with the error characters from the
  154.  * last failing conversion.
  155.  * @param converter: the Unicode converter
  156.  * @param errBytes: the bytes in error
  157.  * @param len: on input the capacity of errBytes, on output the number of bytes copied to it
  158.  * @param  err: the outgoing error status code.
  159.  * If the substitution character array is too small, an
  160.  * <TT>U_INDEX_OUTOFBOUNDS_ERROR</TT> will be returned.
  161.  */
  162.  
  163. U_CAPI void U_EXPORT2
  164.     ucnv_getInvalidChars (const UConverter * converter,
  165.               char *errBytes,
  166.               int8_t * len,
  167.               UErrorCode * err);
  168.  
  169.  
  170. /**
  171.  * Fills in the output parameter, errChars, with the error characters from the
  172.  * last failing conversion.
  173.  * @param converter: the Unicode converter
  174.  * @param errUChars: the bytes in error
  175.  * @param len: on input the capacity of errUChars, on output the number of UChars copied to it
  176.  * @param  err: the outgoing error status code.
  177.  * If the substitution character array is too small, an
  178.  * <TT>U_INDEX_OUTOFBOUNDS_ERROR</TT> will be returned.
  179.  */
  180.  
  181. U_CAPI void U_EXPORT2
  182.     ucnv_getInvalidUChars (const UConverter * converter,
  183.                char *errUChars,
  184.                int8_t * len,
  185.                UErrorCode * err);
  186.  
  187. /**
  188.  * Resets the state of stateful conversion to the default state. This is used
  189.  * in the case of error to restart a conversion from a known default state.
  190.  * it will also empty the internal output buffers.
  191.  * @param converter the Unicode converter
  192.  */
  193.  
  194. U_CAPI void U_EXPORT2
  195.     ucnv_reset (UConverter * converter);
  196.  
  197. /**
  198.  * Returns the maximum length of bytes used by a character. This varies between 1 and 4
  199.  * @param converter the Unicode converter
  200.  * @return the maximum number of bytes allowed by this particular converter
  201.  * @see ucnv_getMinCharSize
  202.  */
  203. U_CAPI int8_t U_EXPORT2
  204.     ucnv_getMaxCharSize (const UConverter * converter);
  205.  
  206.  
  207. /**
  208.  * Returns the minimum byte length for characters in this codepage. This is either
  209.  * 1 or 2 for all supported codepages.
  210.  * @param converter the Unicode converter
  211.  * @return the minimum number of bytes allowed by this particular converter
  212.  * @see ucnv_getMaxCharSize
  213.  */
  214. U_CAPI int8_t U_EXPORT2
  215.     ucnv_getMinCharSize (const UConverter * converter);
  216.  
  217.  
  218. /**
  219.  * Returns the display name of the converter passed in based on the Locale passed in,
  220.  * in the case the locale contains no display name, the internal ASCII name will be
  221.  * filled in.
  222.  * @param converter the Unicode converter.
  223.  * @param displayLocale is the specific Locale we want to localised for
  224.  * @param displayName user provided buffer to be filled in
  225.  * @param displayNameCapacty size of displayName Buffer
  226.  * @param err: outgoing error code.
  227.  * @return displayNameLength number of UChar needed in displayName
  228.  * @see ucnv_getName
  229.  */
  230. U_CAPI
  231.   int32_t U_EXPORT2 ucnv_getDisplayName (const UConverter * converter,
  232.                    const char *displayLocale,
  233.                    UChar * displayName,
  234.                    int32_t displayNameCapacity,
  235.                    UErrorCode * err);
  236.  
  237. /**
  238.  * Gets the name of the converter (zero-terminated).
  239.  * the name will be the internal name of the converter, the lifetime of the returned
  240.  * string will be that of the converter passed to this function.
  241.  * @param converter the Unicode converter
  242.  * @param err UErrorCode status
  243.  * @return the internal name of the converter
  244.  * @see ucnv_getDisplayName
  245.  */
  246. U_CAPI
  247.   const char * U_EXPORT2 ucnv_getName (const UConverter * converter, UErrorCode * err);
  248.  
  249.  
  250. /**
  251.  * Gets a codepage number associated with the converter. This is not guaranteed
  252.  * to be the one used to create the converter. Some converters do not represent
  253.  * IBM registered codepages and return zero for the codepage number.
  254.  * The error code fill-in parameter indicates if the codepage number is available.
  255.  * @param converter the Unicode converter
  256.  * @param err the error status code.
  257.  * the converter is <TT>NULL</TT> or if converter's data table is <TT>NULL</TT>.
  258.  * @return If any error occurrs, -1 will be returned otherwise, the codepage number
  259.  * will be returned
  260.  */
  261. U_CAPI int32_t U_EXPORT2
  262.     ucnv_getCCSID (const UConverter * converter,
  263.            UErrorCode * err);
  264.  
  265. /**
  266.  * Gets a codepage platform associated with the converter. Currently, only <TT>IBM</TT> is supported
  267.  * The error code fill-in parameter indicates if the codepage number is available.
  268.  * @param converter the Unicode converter
  269.  * @param err the error status code.
  270.  * the converter is <TT>NULL</TT> or if converter's data table is <TT>NULL</TT>.
  271.  * @return The codepage platform
  272.  */
  273. U_CAPI UConverterPlatform U_EXPORT2
  274.     ucnv_getPlatform (const UConverter * converter,
  275.               UErrorCode * err);
  276.  
  277. /**
  278.  *Gets the type of conversion associated with the converter
  279.  * e.g. SBCS, MBCS, DBCS, UTF8, UTF16_BE, UTF16_LE, ISO_2022, EBCDIC_STATEFUL, LATIN_1
  280.  * @param converter: a valid, opened converter
  281.  * @return the type of the converter
  282.  */
  283. U_CAPI UConverterType U_EXPORT2
  284. ucnv_getType (const UConverter * converter);
  285.  
  286. /**
  287.  *Gets the "starter" bytes for the converters of type MBCS
  288.  *will fill in an <TT>U_ILLEGAL_ARGUMENT_ERROR</TT> if converter passed in
  289.  *is not MBCS.
  290.  *fills in an array of boolean, with the value of the byte as offset to the array.
  291.  *At return, if TRUE is found in at offset 0x20, it means that the byte 0x20 is a starter byte
  292.  *in this converter.
  293.  * @param converter: a valid, opened converter of type MBCS
  294.  * @param starters: an array of size 256 to be filled in
  295.  * @param err: an array of size 256 to be filled in
  296.  * @see ucnv_getType
  297.  */
  298. U_CAPI void U_EXPORT2 ucnv_getStarters(const UConverter* converter, 
  299.                      bool_t starters[256],
  300.                      UErrorCode* err);
  301.  
  302.  
  303. /**
  304.  * Gets the current calback function used by the converter when illegal or invalid sequence found.
  305.  * @param converter the unicode converter
  306.  * @return a pointer to the callback function
  307.  * @see ucnv_setToUCallBack
  308.  */
  309. U_CAPI UConverterToUCallback U_EXPORT2
  310.     ucnv_getToUCallBack (const UConverter * converter);
  311.  
  312. /**
  313.  * Gets the current callback function used by the converter when illegal or invalid sequence found.
  314.  * @param converter the unicode converter
  315.  * @return a pointer to the callback function
  316.  * @see ucnv_setFromUCallBack
  317.  */
  318. U_CAPI UConverterFromUCallback U_EXPORT2
  319.     ucnv_getFromUCallBack (const UConverter * converter);
  320.  
  321. /**
  322.  * Gets the current callback function used by the converter when illegal or invalid sequence found
  323.  * @param converter the unicode converter
  324.  * @param action the callback function we want to set.
  325.  * @param err The error code status
  326.  * @return the previously assigned callback function pointer
  327.  * @see ucnv_getToUCallBack
  328.  */
  329. U_CAPI UConverterToUCallback U_EXPORT2
  330.     ucnv_setToUCallBack (UConverter * converter,
  331.              UConverterToUCallback action,
  332.              UErrorCode * err);
  333.  
  334. /**
  335.  * Gets the current callback function used by the converter when illegal or invalid sequence found
  336.  * @param converter the unicode converter
  337.  * @param action the callback function we want to set.
  338.  * @param err The error code status
  339.  * @return the previously assigned callback function pointer
  340.  * @see ucnv_getFromUCallBack
  341.  */
  342. U_CAPI UConverterFromUCallback U_EXPORT2
  343.     ucnv_setFromUCallBack (UConverter * converter,
  344.                UConverterFromUCallback action,
  345.                UErrorCode * err);
  346.  
  347.  
  348. /**
  349.  * Transcodes an array of unicode characters to an array of codepage characters.
  350.  * The source pointer is an I/O parameter, it starts out pointing where the function is
  351.  * to begin transcoding, and ends up pointing after the first sequence of the bytes
  352.  * that it encounters that are semantically invalid.
  353.  * if ucnv_setToUCallBack is called with an action other than <TT>STOP</TT>
  354.  * before a call is made to this API, <TT>consumed</TT> and <TT>source</TT> should point to the same place
  355.  * (unless <TT>target</TT> ends with an imcomplete sequence of bytes and <TT>flush</TT> is <TT>FALSE</TT>).
  356.  * the <TT>target</TT> buffer buffer needs to be a least the size of the maximum # of bytes per characters
  357.  * allowed by the target codepage.
  358.  * @param converter the Unicode converter
  359.  * @param converter the Unicode converter
  360.  * @param target : I/O parameter. Input : Points to the beginning of the buffer to copy
  361.  *  codepage characters to. Output : points to after the last codepage character copied
  362.  *  to <TT>target</TT>.
  363.  * @param targetLimit the pointer to the end of the <TT>target</TT> array
  364.  * @param source the source Unicode character array
  365.  * @param sourceLimit the pointer to the end of the source array
  366.  * @param offsets if NULL is passed, nothing will happen to it, otherwise it needs to have the same number
  367.  * of allocated cells as <TT>target</TT>. Will fill in offsets from target to source pointer
  368.  * e.g: <TT>offsets[3]</TT> is equal to 6, it means that the <TT>target[3]</TT> was a result of transcoding <TT>source[6]</TT>
  369.  * For output data carried across calls -1 will be placed for offsets.
  370.  * @param flush <TT>TRUE</TT> if the buffer is the last buffer of the conversion interation
  371.  * and the conversion will finish with this call, FALSE otherwise.
  372.  * @param err the error status.  <TT>U_ILLEGAL_ARGUMENT_ERROR</TT> will be returned if the
  373.  * converter is <TT>NULL</TT>.
  374.  * @see ucnv_fromUChars
  375.  * @see ucnv_convert
  376.  * @see ucnv_getMinCharSize
  377.  * @see ucnv_setToUCallBack
  378.  */
  379.  
  380. U_CAPI
  381.   void U_EXPORT2 ucnv_fromUnicode (UConverter * converter,
  382.              char **target,
  383.              const char *targetLimit,
  384.              const UChar ** source,
  385.              const UChar * sourceLimit,
  386.              int32_t* offsets,
  387.              bool_t flush,
  388.              UErrorCode * err);
  389.  
  390.  
  391. /**
  392.  * Converts an array of codepage characters into an array of unicode characters.
  393.  * The source pointer is an I/O parameter, it starts out pointing at the place
  394.  * to begin translating, and ends up pointing after the first sequence of the bytes
  395.  * that it encounters that are semantically invalid.
  396.  * if ucnv_setFromUCallBack is called with an action other than STOP
  397.  * before a call is made to this API, consumed and source should point to the same place
  398.  * (unless target ends with an imcomplete sequence of bytes and flush is FALSE).
  399.  * @param converter the Unicode converter
  400.  * @param target : I/O parameter. Input : Points to the beginning of the buffer to copy
  401.  *  Unicode characters to. Output : points to after the last UChar copied to target.
  402.  * @param targetLimit the pointer to the end of the target array
  403.  * @param source the source codepage character array
  404.  * @param sourceLimit the pointer to the end of the source array
  405.  * @param offsets if NULL is passed, nothing will happen to it, otherwise it needs to have the same number
  406.  * of allocated cells as <TT>target</TT>. Will fill in offsets from target to source pointer
  407.  * e.g: <TT>offsets[3]</TT> is equal to 6, it means that the <TT>target[3]</TT> was a result of transcoding <TT>source[6]</TT>
  408.  * For output data carried across calls -1 will be placed for offsets.
  409.  * @param flush TRUE if the buffer is the last buffer and the conversion will finish
  410.  * in this call, FALSE otherwise. 
  411.  * @param err the error code status  <TT>U_ILLEGAL_ARGUMENT_ERROR</TT> will be returned if the
  412.  * converter is <TT>NULL</TT>, or if <TT>targetLimit</TT> and <TT>sourceLimit</TT> are misaligned.
  413.  * @see ucnv_toUChars
  414.  * @see ucnv_getNextUChar
  415.  * @see ucnv_convert
  416.  * @see ucnv_setFromUCallBack
  417.  */
  418.  
  419. U_CAPI
  420.   void U_EXPORT2 ucnv_toUnicode (UConverter * converter,
  421.                UChar ** target,
  422.                const UChar * targetLimit,
  423.                const char **source,
  424.                const char *sourceLimit,
  425.                int32_t* offsets,
  426.                bool_t flush,
  427.                UErrorCode * err);
  428.  
  429.  
  430. /**
  431.  * Transcodes the source Unicode string to the target string in a codepage encoding
  432.  * with the specified Unicode converter.  For example, if a Unicode to/from JIS
  433.  * converter is specified, the source string in Unicode will be transcoded to JIS
  434.  * encoding.  The result will be stored in JIS encoding.
  435.  * if any problems during conversion are encountered it will SUBSTITUTE with the default (initial)
  436.  * substitute characters.
  437.  * This function is a more convenient but less efficient version of \Ref{ucnv_fromUnicode}.
  438.  * @param converter the Unicode converter
  439.  * @param source the <TT>source</TT> Unicode string (zero Terminated)
  440.  * @param target the <TT>target</TT> string in codepage encoding (<STRONG>not zero-terminated</STRONG> because some
  441.  * codepage do not use '\0' as a string terminator
  442.  * @param targetCapacity Input the number of bytes available in the <TT>target</TT> buffer
  443.  * @param err the error status code.
  444.  * <TT>U_INDEX_OUTOFBOUNDS_ERROR</TT> will be returned if the
  445.  * the # of bytes provided are not enough for transcoding.
  446.  * <TT>U_ILLEGAL_ARGUMENT_ERROR</TT> is returned if the converter is <TT>NULL</TT> or the source or target string is empty.
  447.  * <TT>U_BUFFER_OVERFLOW_ERROR</TT> when <TT>targetSize</TT> turns out to be bigger than <TT>targetCapacity</TT>
  448.  * @return number of bytes needed in target, regardless of <TT>targetCapacity</TT>
  449.  * @see ucnv_fromUnicode
  450.  * @see ucnv_convert
  451.  */
  452. U_CAPI
  453.   int32_t U_EXPORT2 ucnv_fromUChars (const UConverter * converter,
  454.                char *target,
  455.                int32_t targetCapacity,
  456.                const UChar * source,
  457.                UErrorCode * err);
  458.  
  459.  
  460.  
  461.  
  462.  
  463. /**
  464.  * Transcode the source string in codepage encoding to the target string in
  465.  * Unicode encoding.  For example, if a Unicode to/from JIS
  466.  * converter is specified, the source string in JIS encoding will be transcoded
  467.  * to Unicode and placed into a provided target buffer.
  468.  * if any problems during conversion are encountered it will SUBSTITUTE with the Unicode REPLACEMENT char
  469.  * We recomment, the size of the target buffer needs to be at least as long as the maximum # of bytes per char
  470.  * in this character set.
  471.  * A zero-terminator will be placed at the end of the target buffer
  472.  * This function is a more convenient but less efficient version of \Ref{ucnv_toUnicode}.
  473.  * @param converter the Unicode converter
  474.  * @param source the source string in codepage encoding
  475.  * @param target the target string in Unicode encoding
  476.  * @param targetCapacity capacity of the target buffer
  477.  * @param sourceSize : Number of bytes in <TT>source</TT> to be transcoded
  478.  * @param err the error status code
  479.  * <TT>U_MEMORY_ALLOCATION_ERROR</TT> will be returned if the
  480.  * the internal process buffer cannot be allocated for transcoding.
  481.  * <TT>U_ILLEGAL_ARGUMENT_ERROR</TT> is returned if the converter is <TT>NULL</TT> or
  482.  * if the source or target string is empty.
  483.  * <TT>U_BUFFER_OVERFLOW_ERROR</TT> when the input buffer is prematurely exhausted and targetSize non-<TT>NULL</TT>.
  484.  * @return the number of UChar needed in target (including the zero terminator)
  485.  * @see ucnv_getNextUChar
  486.  * @see ucnv_toUnicode
  487.  * @see ucnv_convert
  488.  */
  489. U_CAPI
  490.   int32_t U_EXPORT2 ucnv_toUChars (const UConverter * converter,
  491.              UChar * target,
  492.              int32_t targetCapacity,
  493.              const char *source,
  494.              int32_t sourceSize,
  495.              UErrorCode * err);
  496.  
  497. /********************************
  498.  * Will convert a codepage buffer one character at a time.
  499.  * This function was written to be efficient when transcoding small amounts of data at a time.
  500.  * In that case it will be more efficient than \Ref{ucnv_toUnicode}.
  501.  * When converting large buffers use \Ref{ucnv_toUnicode}.
  502.  *@param converter an open UConverter
  503.  *@param source the address of a pointer to the codepage buffer, will be updated to point after
  504.  *the bytes consumed in the conversion call.
  505.  *@param points to the end of the input buffer
  506.  *@param err fills in error status (see ucnv_toUnicode)
  507.  *@return a UChar resulting from the partial conversion of source
  508.  *@see ucnv_toUnicode
  509.  *@see ucnv_toUChars
  510.  *@see ucnv_convert
  511.  */
  512. U_CAPI
  513.   UChar U_EXPORT2 ucnv_getNextUChar (UConverter * converter,
  514.                const char **source,
  515.                const char *sourceLimit,
  516.                UErrorCode * err);
  517.  
  518.  
  519. /**************************
  520. * Will convert a sequence of bytes from one codepage to another.
  521. * This is <STRONG>NOT AN EFFICIENT</STRONG> way to transcode.
  522. * use \Ref{ucnv_toUnicode} and \Ref{ucnv_fromUnicode} for efficiency
  523. * @param toConverterName: The name of the converter that will be used to encode the output buffer
  524. * @param fromConverterName: The name of the converter that will be used to decode the input buffer
  525. * @param target: Pointer to the output buffer to write to
  526. * @param targetCapacity: on input contains the capacity of target
  527. * @param source: Pointer to the input buffer
  528. * @param sourceLength: on input contains the capacity of source
  529. * @param err: fills in an error status
  530. * @return  will be filled in with the number of bytes needed in target
  531. * @see ucnv_fromUnicode
  532. * @see ucnv_toUnicode
  533. * @see ucnv_fromUChars
  534. * @see ucnv_toUChars
  535. * @see ucnv_getNextUChar
  536. */
  537. U_CAPI
  538.   int32_t U_EXPORT2 ucnv_convert (const char *toConverterName,
  539.             const char *fromConverterName,
  540.             char *target,
  541.             int32_t targetCapacity,
  542.             const char *source,
  543.             int32_t sourceLength,
  544.             UErrorCode * err);
  545.  
  546. /**
  547.  * SYSTEM API
  548.  * Iterates through every cached converter and frees all the unused ones.
  549.  * @return the number of cached converters successfully deleted
  550.  */
  551. U_CAPI int32_t U_EXPORT2 ucnv_flushCache (void);
  552.  
  553.  
  554. /**
  555.  * provides a string containing the internal name (based on the alias file) of the converter.
  556.  * given an index.
  557.  * @param index the number of converters available on the system (<TT>[0..ucnv_countAvaiable()]</TT>)
  558.  * @return a pointer a string (library owned), or <TT>NULL</TT> if the index is out of bounds.
  559.  * @see ucnv_countAvailable
  560.  */
  561. U_CAPI
  562.   const char * U_EXPORT2 ucnv_getAvailableName (int32_t index);
  563.  
  564. /**
  565.  * returns the number of available converters.
  566.  * @return the number of available converters
  567.  * @see ucnv_getAvailableName
  568.  */
  569. U_CAPI int32_t U_EXPORT2 ucnv_countAvailable (void);
  570.  
  571. /**
  572.  * returns the current default converter name.
  573.  * @return returns the current default converter name
  574.  * @see ucnv_setDefaultName
  575.  */
  576. U_CAPI const char * U_EXPORT2 ucnv_getDefaultName (void);
  577.  
  578. /**
  579.  * sets the current default converter name.
  580.  * The lifetime of the return ptr is that of the library
  581.  * @param name: the converter name you want as default (has to appear in alias file)
  582.  * @see ucnv_getDefaultName
  583.  *
  584.  */
  585. U_CAPI void U_EXPORT2 ucnv_setDefaultName (const char *name);
  586.  
  587.  
  588. #endif
  589. /*_UCNV*/
  590.